/*
 * File     : NativeObject.java
 * Created  : 1 May 2011
 *
 * Copyright © 2011 Matthew Wilson (mj. {my-surname} .uk {at} gmail.com)
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
package com.googlecode.dni.type;

import com.googlecode.dni.InitialisationOption.Initialisation;

/**
 * <p>
 *  Encapsulates an object that is backed by native memory.
 * </p>
 * <h3>Lifetime Management</h3>
 * <p>
 *  Each and every native object is backed by native memory.  There are four
 *  types of native object lifetime:
 * </p>
 * <ul>
 *  <li>
 *   DNI-allocated (normal):  For any native object that does <em>not</em>
 *   extend {@link LifetimeManagedObject} and is directly allocated by DNI (for
 *   example, creating a new, blank structure instance), the object's native
 *   memory will be freed when the Java object is garbage collected (on
 *   finalization, or equivalent).
 *  </li>
 *  <li>
 *   Created from native (normal):  For any native object that does
 *   <em>not</em> extend {@link LifetimeManagedObject} and is created as a
 *   result of a read of a pointer (for example, from a structure or the return
 *   value of a function), the lifetime is considered to be controlled by native
 *   code (or custom user code), and the structure's native memory is
 *   <em>not</em> freed automatically by DNI.  However, DNI tracks all
 *   DNI-allocated native objects and will return the very same Java instance
 *   for a recognised pointer.
 *  </li>
 *  <li>
 *   Explicitly managed:  For any native object that extends
 *   {@link LifetimeManagedObject}, regardless of how it is created, will need
 *   explicit freeing via {@link LifetimeManagedObject#free()}.  It is up to the
 *   user of DNI to track the lifetime of the object (including whether it is
 *   retained and then dropped by native code) and free it when necessary.
 *   Freeing an object will always assume that the memory was allocated via the
 *   same mechanism that is used by DNI to allocate memory (this is
 *   <code>malloc</code> and <code>free</code> by default, but can be
 *   {@linkplain Initialisation#init overridden}).
 *  </li>
 * </ul>
 * <p>
 *  (DNI attempts to prevent double-freeing of the same object, but the
 *  mechanism is not guaranteed to be thread-safe or fool-proof; it should not
 *  be relied upon for correctness.)
 * </p>
 * <h3>Notice</h3>
 * <p>
 *  <strong>
 *   This type is not intended for general extension by users of DNI.
 *  </strong>
 * </p>
 *
 * @author Matthew Wilson
 */
public interface NativeObject
{

    /**
     * <p>
     *  Obtains the native pointer of the structure.
     * </p>
     *
     * @return the pointer to the base of the structure
     */
    Pointer pointer();

    /**
     * <p>
     *  Determines whether the given object is the same as this object.
     * </p>
     * <p>
     *  Under many circumstances, it is inappropriate to use Java's identity
     *  equals <code>==</code> or {@link #equals(Object)} to determine whether
     *  two objects are the same.  This method is equivalent to:
     * </p>
     * <pre>
     *  this.pointer().equals( other.pointer() )
     * </pre>
     *
     * @param other
     *            the other object; must not be <code>null</code>
     *
     * @return <code>true</code> iff the pointer of the given object is the
     *         same as the pointer of this object
     */
    boolean isSameObject( NativeObject other );

}
